0243. include 和 exclude
- 1. 🎯 本节内容
- 2. 🫧 评价
- 3. 🤔 include 和 exclude 是什么?
- 4. 🤔 如何使用 glob 模式?
- 5. 🆚 include vs. exclude
- 6. 🤔 常见配置场景?
- 7. 🤔 使用时需要注意什么?
- 8. 🔗 引用
1. 🎯 本节内容
- include 包含规则
- exclude 排除规则
- glob 模式语法
- 优先级规则
- 默认行为
- 常见配置模式
2. 🫧 评价
include 和 exclude 控制哪些文件被编译,是项目文件管理的核心配置。
- include 指定要编译的文件
- exclude 排除不需要的文件
- 支持 glob 模式匹配
- 有明确的优先级规则
- 默认值需要注意
- 合理配置提高编译效率
3. 🤔 include 和 exclude 是什么?
3.1. include
指定要包含在编译中的文件或目录模式。
json
{
"include": ["src/**/*", "types/**/*"]
}1
2
3
2
3
3.2. exclude
指定要排除的文件或目录模式。
json
{
"exclude": ["node_modules", "dist", "**/*.spec.ts"]
}1
2
3
2
3
3.3. 基本示例
text
项目结构:
my-project/
├── src/
│ ├── index.ts
│ ├── utils.ts
│ └── test.spec.ts
├── dist/
├── node_modules/
└── tsconfig.json1
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
json
{
"compilerOptions": {
"outDir": "./dist"
},
"include": ["src/**/*"],
"exclude": ["**/*.spec.ts", "node_modules", "dist"]
}1
2
3
4
5
6
7
2
3
4
5
6
7
text
编译文件:
✅ src/index.ts
✅ src/utils.ts
❌ src/test.spec.ts (被 exclude)
❌ node_modules/**
❌ dist/**1
2
3
4
5
6
2
3
4
5
6
4. 🤔 如何使用 glob 模式?
4.1. 基本通配符
json
{
"include": [
"*", // 匹配当前目录所有文件
"*.ts", // 匹配所有 .ts 文件
"src/*", // 匹配 src 下一层文件
"src/**/*", // 匹配 src 下所有文件(递归)
"**/*.ts" // 匹配所有 .ts 文件(递归)
]
}1
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
4.2. ? 单字符匹配
json
{
"include": [
"src/file?.ts" // 匹配 file1.ts, fileA.ts
]
}1
2
3
4
5
2
3
4
5
4.3. ** 递归目录
json
{
"include": [
"src/**/*.ts", // 匹配 src 下所有 .ts 文件
"**/components/*" // 匹配任意深度的 components 目录
]
}1
2
3
4
5
6
2
3
4
5
6
4.4. 多种扩展名
json
{
"include": [
"src/**/*.{ts,tsx}" // 匹配 .ts 和 .tsx
]
}1
2
3
4
5
2
3
4
5
4.5. 排除特定文件
json
{
"exclude": [
"**/*.spec.ts", // 所有测试文件
"**/*.test.ts", // 所有测试文件
"**/__tests__/**" // 测试目录
]
}1
2
3
4
5
6
7
2
3
4
5
6
7
5. 🆚 include vs. exclude
| 特性 | include | exclude |
|---|---|---|
| 作用 | 指定包含的文件 | 指定排除的文件 |
| 默认值 | ["**/*"] | ["node_modules", "bower_components", "jspm_packages", outDir] |
| 优先级 | 低于 files | 高于 include |
| 必需性 | 可选 | 可选 |
| 适用范围 | 主动选择文件 | 过滤不需要的文件 |
| 常见用途 | 指定源码目录 | 排除构建产物、依赖 |
5.1. 优先级规则
text
files > exclude > include
1. files 明确指定的文件,始终包含
2. exclude 排除的文件,不会编译
3. include 包含的文件,但可被 exclude 排除1
2
3
4
5
2
3
4
5
6. 🤔 常见配置场景?
6.1. 标准项目
json
{
"compilerOptions": {
"outDir": "./dist"
},
"include": ["src/**/*"],
"exclude": ["node_modules", "dist", "**/*.spec.ts"]
}1
2
3
4
5
6
7
2
3
4
5
6
7
6.2. 多源目录
json
{
"include": ["src/**/*", "lib/**/*", "types/**/*"],
"exclude": ["node_modules", "**/*.test.ts"]
}1
2
3
4
2
3
4
6.3. Monorepo
json
{
"include": ["packages/*/src/**/*"],
"exclude": ["packages/*/dist", "packages/*/node_modules", "**/*.spec.ts"]
}1
2
3
4
2
3
4
6.4. 包含测试文件
json
// 开发环境
{
"include": [
"src/**/*",
"test/**/*"
]
}
// 生产构建
{
"include": [
"src/**/*"
],
"exclude": [
"**/*.spec.ts",
"test/**/*"
]
}1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
6.5. 类型声明文件
json
{
"include": [
"src/**/*",
"types/**/*.d.ts" // 包含自定义类型声明
],
"exclude": [
"node_modules/@types" // 排除特定类型包
]
}1
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
6.6. 脚本和配置
json
{
"include": ["src/**/*"],
"exclude": [
"scripts/**/*", // 排除构建脚本
"config/**/*", // 排除配置文件
"*.config.js" // 排除根配置
]
}1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
6.7. 文档和示例
json
{
"include": ["src/**/*"],
"exclude": ["docs/**/*", "examples/**/*", "**/*.md"]
}1
2
3
4
2
3
4
7. 🤔 使用时需要注意什么?
7.1. 默认 exclude
json
// 如果不指定 exclude,默认为:
{
"exclude": [
"node_modules",
"bower_components",
"jspm_packages",
"./dist" // 如果设置了 outDir
]
}
// ⚠️ 一旦指定 exclude,默认值失效
{
"exclude": [
"**/*.spec.ts" // ❌ node_modules 不再自动排除
]
}
// ✅ 正确做法:显式包含默认值
{
"exclude": [
"node_modules",
"dist",
"**/*.spec.ts"
]
}1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
7.2. include 和 files 的关系
json
{
"files": [
"src/main.ts" // 始终包含,不受 exclude 影响
],
"include": ["src/**/*"],
"exclude": [
"src/main.ts" // ⚠️ 无效,files 优先级更高
]
}1
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
7.3. 路径解析
json
{
// ✅ 相对于 tsconfig.json 所在目录
"include": [
"./src/**/*", // 推荐显式相对路径
"src/**/*" // 也可以省略 ./
],
// ❌ 不支持绝对路径
"include": [
"/Users/username/project/src/**/*" // 影响可移植性
]
}1
2
3
4
5
6
7
8
9
10
11
12
2
3
4
5
6
7
8
9
10
11
12
7.4. 性能优化
json
{
// ✅ 精确的 include 提高性能
"include": ["src/**/*.ts", "src/**/*.tsx"],
// ⚠️ 过于宽泛影响性能
"include": [
"**/*" // 扫描所有文件
]
}1
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
7.5. 隐藏文件
json
{
"include": ["src/**/*"],
// ✅ 默认排除以 . 开头的文件
// .cache/
// .temp/
// 如需包含,需显式指定
"include": ["src/**/*", ".config/**/*"]
}1
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
7.6. 符号链接
text
项目:
src/
utils/ -> ../shared/utils (符号链接)
shared/
utils/1
2
3
4
5
2
3
4
5
json
{
"compilerOptions": {
"preserveSymlinks": true // 保留符号链接
},
"include": [
"src/**/*",
"shared/**/*" // 需要包含实际目录
]
}1
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
7.7. 与 tsconfig.json 位置
text
项目结构:
my-project/
├── frontend/
│ ├── src/
│ └── tsconfig.json
└── backend/
├── src/
└── tsconfig.json1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
json
// frontend/tsconfig.json
{
"include": [
"src/**/*" // 相对于 frontend/
]
}
// backend/tsconfig.json
{
"include": [
"src/**/*" // 相对于 backend/
]
}1
2
3
4
5
6
7
8
9
10
11
12
13
2
3
4
5
6
7
8
9
10
11
12
13
7.8. 构建工具集成
json
// 与 webpack 配合
{
"include": [
"src/**/*"
],
"exclude": [
"node_modules",
"webpack.config.js"
]
}
// 与 Jest 配合
{
"include": [
"src/**/*",
"test/**/*"
],
"exclude": [
"**/*.spec.ts" // Jest 单独处理
]
}1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
7.9. 类型检查范围
json
{
// ✅ 只检查源码
"include": ["src/**/*"],
// ⚠️ 包含太多文件降低性能
"include": [
"src/**/*",
"node_modules/**/*" // 通常不需要
]
}1
2
3
4
5
6
7
8
9
10
2
3
4
5
6
7
8
9
10
7.10. extends 继承
json
// tsconfig.base.json
{
"include": [
"src/**/*"
],
"exclude": [
"node_modules"
]
}
// tsconfig.json
{
"extends": "./tsconfig.base.json",
// ⚠️ include/exclude 不会合并,会完全覆盖
"include": [
"src/**/*",
"test/**/*" // 覆盖基础配置
]
}1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19